home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / windowtc.arc / QUTIL10.DOC < prev    next >
Text File  |  1987-06-20  |  15KB  |  337 lines
  1.                                                         December 09, 1986
  2.  
  3.                                Q SCREEN UTILITIES
  4.                              TURBO-C   Version 1.0
  5.  
  6.         PURPOSE:
  7.  
  8.         Q screen utilities permit fast screen writes on IBM compatibles
  9.         with MDA, CGA, and/or EGA adapters without "snow" or flicker
  10.         effects and is compatible with ANY column format (e.g. 40/80 or
  11.         variable).  Written in Microsoft macro-assembler, these C
  12.         functions are lightning fast.  The code has also been condensed
  13.         as much as possible without sacrificing speed - only 1.6k bytes
  14.         of compiled code for all 20 functions!
  15.  
  16.  
  17.         TEST DRIVE:
  18.  
  19.         Compile and run QDEMO10.C to get a feel for features and speed.
  20.  
  21.  
  22.         IMPROVEMENTS:
  23.  
  24.         The original inline Turbo Pascal code was converted to C calling
  25.         assembler functions using the rules.asi macro file supplied with
  26.         TURBO-C. The assembler code has been revised to allow
  27.         column formats of ANY size (e.g. 40,80, or variable) and allow
  28.         global access to addresses and wait-for-retrace.  This gives you
  29.         the power to have multiple pages (4 on CGA and 8 on EGA) in memory
  30.         that you already have.  The filling and transfer procedures now
  31.         work in block mode rather than line mode which is faster and much
  32.         simpler with the use of Rows-by-Columns parameters.
  33.  
  34.         UTILITIES:
  35.  
  36.         In this version, WIND10S.LIB contains:
  37.  
  38.            qinit():  Initializing procedure required to be called
  39.                          before all Q utilities.  Also has a function to
  40.                          check for EGA cards.
  41.  
  42.                      Five Quick direct screen writing functions:
  43.  
  44.                          qwritelv() - referenced (var) strings, specified
  45.                                       length and index.
  46.                          qwritev()  - referenced (var) strings
  47.                          qwrite()   - value strings
  48.                          qwritec()  - value strings, self-centering
  49.                          qwritecv() - referenced (VAR) strings, self-
  50.                                       centering
  51.  
  52.                       Four Quick direct screen filling procedures
  53.                       in Rows-by-Cols block functions:
  54.  
  55.                          qfillc()   - repetitive filling with the same
  56.                                       character and self-centering
  57.                          qfill()    - repetitive filling with the same
  58.                                       character
  59.                          qattr()    - repetitive filling with the same
  60.                                       attribute only
  61.                          qattrc()   - repetitive filling with the same
  62.                                       attribute and self-centering
  63.  
  64.                       Two Quick storing functions:
  65.  
  66.                          qstore() - Saves a Rows-by-Cols block
  67.                                   to memory.
  68.                          qrestore() - Restores a Rows-by-Cols block
  69.                                     to any screen page.
  70.  
  71.                       Two Quick direct screen changing functions:
  72.                          qpage()  - Changes the page to be
  73.                                   displayed - up to 8!
  74.                          qwritepage() - Sets the page on which the
  75.                                       Q utilities are writing.  You
  76.                                       don't have to write just on
  77.                                       the displayed page!
  78.  
  79.                       Four Quick cursor functions:
  80.  
  81.                          gotorc()       - go to row/col any page
  82.                          changecursor() - changes shape and visibility
  83.                                           of the cursor; saves old, too!
  84.                           wherex() -- returns current cursor column position
  85.                           wherey() -- returns cuurent cursor row position
  86.  
  87.                       Miscellaneous functions:
  88.                           egacheck() -- returns 1 if ega monitor
  89.                           wiattr() -- returns attribute of fore/back color
  90.                           qbox() -- draws a box on screen
  91.  
  92.  
  93.         PROGRAMMING:
  94.  
  95.         To use the functions, just simply include <WINDPROT.H> in any of
  96.         your application rograms.  <W1.h>  must be included first.
  97.         Only one initializing statement is necessary qinit() before the 
  98.         Q utilities are used (not required for cursor.inc):
  99.  
  100.             Qinit();
  101.  
  102.         This procedure automatically configures the procedures to your
  103.         machine and also makes it portable to others.
  104.  
  105.  
  106.        MODULES:
  107.  
  108.         The coding has been reduced by making the display loops into an
  109.         assembler subroutine and programming the functions to access it.
  110.         via a CALL address. One such subroutine is present for QFILL, and
  111.         QWRITE .
  112.  
  113.  
  114.         PARAMETERS:
  115.  
  116.         row/col - The functions do not check for bounds on the screen,
  117.         so be sure to stay in range.  The functions were designed for
  118.         the upper left column on the screen to be 1,1. They also wrap to
  119.         the next line; they do not truncate at EOL.  You of course can
  120.         have something like Row:=1 and Col:=255 which is equivalent to 
  121.         row=3 and col=15 on a screen with 80 columns.
  122.  
  123.         coll/colr - In qwritec, qwritecv, qfillc, and qattrc, the left
  124.         and right columns are simply averaged.  To center on the full
  125.         width of an 80 column display, set coll:=1 and colr:=80.  To
  126.         center on a certain column number, set both values equal to that
  127.         column number.
  128.  
  129.         rows/cols - They can be any positive integer to define the block
  130.         - Rows-by-Columns starting at row, col.  Values <=0 will simply
  131.         abort the function.  Please keep cols limited to one row.
  132.  
  133.         attr - The attributes range from 0 to 255.  Values greater than
  134.         255 will be operated by modulo 256 to stay useful.  Negative
  135.         values suppress any changes to the screen attributes and use
  136.         what's currently on the screen.  For help with attribute values,
  137.         use Brian Foley's FWATTR.INC on Borland's Programming Forum on
  138.         CompuServe in Turbo Pascal Data Library for MSDOS.
  139.  
  140.         length - In qwritelv, you can write partial strings by specifying
  141.         the Length and starting index (St[i]).  All other qwrite procedures
  142.         assume the string to be null terminated. Length can be any positive 
  143.         integer.
  144.  
  145.         st - The original type was set for string length of 80 characters
  146.         which my be changed to any value between 1 and 255.  Be sure to
  147.         change all type statements to reflect it though!
  148.  
  149.         source/dest - For qstore/restore this can be a pointer for the heap
  150.         or an array variable.  Be sure there is sufficient room.  Storage
  151.         requirements are: (rows * cols << 1) which is two bytes for
  152.         every column (one for character one for attribute):
  153.  
  154.                      EXAMPLES:
  155.  
  156.             char store_array[4000];
  157.                  --OR--
  158.             char *store_array;
  159.             store_array = (char *)malloc(((rows * cols) << 1)*(sizeof(char)));
  160.  
  161.             qstore (row,col,rows,cols,store_array);
  162.             qrestore (row,col,rows,cols,store_array);
  163.  
  164.         page - The page range depends upon your adapter as follows:
  165.                MDA - On Monochrome cards, there is only page 0.
  166.                CGA - Page 0 to 3 in modes 2 and 3 (80 column),
  167.                      page 0 to 7 in modes 0 and 1 (40 column).
  168.                EGA - Page 0 to 7 in any mode (as I understand it).
  169.  
  170.         foreground/background -- can be any of the colors listed in COLOR.H
  171.  
  172.         btype -- can be any border type defined in (w1.h) BORDERS.
  173.  
  174.  
  175.         PAGING:
  176.  
  177.         If you have a CGA or better, you already have memory on your card
  178.         for more than the 80x25 display you normally see.  The two page
  179.         procedures allow you to use Q screen utilities on these other pages
  180.         and display which ever you choose.  However, Turbo-C's functions
  181.         such as printf,fprintf,puts,putch are dedicated to page 0 only.
  182.         I have included gotorc as one utility that works on all pages. 
  183.         Be sure to end your programs with "qpage (0);".
  184.  
  185.  
  186.         SPEED:
  187.  
  188.         How fast is fast?  Well, I thought it would be good idea to have
  189.         some criteria to get a feeling for speed.  The units I decided
  190.         to use for comparison are "screens/second".  To make one screen,
  191.         a utility is repeated with a FOR loop to fill several 80x25
  192.         pages and timed.  qwriteXX use 80 character strings, and qattr
  193.         and qfill use rows=25 and Cols=80.  At the moment, all I have
  194.         are ratings on my own computer (IBM XT -- NEC-V20, HERCULES CARD).
  195.          Other processors will be proportional.  Monochrome (MDA)
  196.         speeds are identical to EGA speeds.
  197.  
  198.         ------------------ S C R E E N S / S E C O N D ------------------
  199.                     Chng -- 80286 --    -- 8086 ---    -- 8088 ---
  200.         Procedure   Attr EGA     CGA    EGA     CGA    EGA     CGA
  201.         ---------   ---- -----------    -----------    ------------
  202.         qwritelv    Yes   35.5   0.0
  203.                     No    44.8   0.0
  204.         qwritev     Yes    7.1   0.0
  205.                     No     7.4   0.0
  206.         qwrite      Yes    7.1   0.0
  207.                     No    21.3   0.0
  208.         qwritec     Yes   18.8   0.0
  209.                     No     7.4   0.0
  210.         qwritecv    Yes    7.1   0.0
  211.                     No    21.1   0.0
  212.         qfillc      Yes  100.4   0.0
  213.                     No    80.9   0.0
  214.         qfill       Yes  100.4   0.0
  215.                     No    83.2   0.0
  216.         qattr       Yes   83.2   0.0
  217.         qattrc      Yes   83.2   0.0
  218.         qstore      N/A    9.8   0.0
  219.         qrestore    N/A   69.4   0.0
  220.         waitscreens= 0  (*COLOR SPECIFIC)
  221.         nowaitscreens= 160
  222.  
  223.  
  224.         HOW IT WAS ASSEMBLED:
  225.  
  226.         Microsoft Macro-Assembler 4.0 and user.asi macro files set up
  227.         to simulate C calling protocol in TURBO-C. User.asi is supplied
  228.         on the TURBO-C disks. I plan to comment the assembler source code
  229.         and release it at a later date, so other users can see how to
  230.         use macros and call assembler functions.
  231.  
  232.         TEAMWARE:
  233.  
  234.         With the release of this utility, I hope to introduce the concept
  235.         of Teamware.  These utilities are FREE, so don't worry.  Many pro-
  236.         grammers have done some superior individual efforts and have
  237.         benefited many.  But the problem is just that - they are individual
  238.         efforts that as packages are not compatible with other individual
  239.         efforts.  And many of the programs are released as copyrighted so
  240.         that others cannot use them in certain contexts.  It seems that if
  241.         users have other expertise and discover ways to combine each others
  242.         utilities, the benefits can improve greatly.  This is what these
  243.         utilities have done.
  244.  
  245.         As Teamware, users CAN and are encouraged to:
  246.  
  247.            1. Use the utilities to enhance their programs and applications
  248.               in both private and commercial contexts.
  249.            2. Combine, create, and edit other utilities and re-release them
  250.               as Teamware by permission of the previous author(s)/editor(s).
  251.            3. Enhance shareware programs provided they are applications that
  252.               in no way represent or advertise the power of the utilities
  253.               themselves, but shall credit the use of Teamware.
  254.            4. Ask about questionable use of the utility.
  255.  
  256.         As Teamware, users CANNOT:
  257.  
  258.            1. Distribute the utilities for profit.
  259.            2. Combine, create, and edit other utilities and re-release them
  260.               as Shareware or for any profit as enhanced utilities.
  261.  
  262.         LIABILITY:
  263.  
  264.         No liabilities are assumed if the user misuses these utilities.
  265.  
  266.  
  267.         CREDITS:
  268.  
  269.         Without the assistance and original ideas from Brian Foley
  270.         [76317,3247], these routines would not have been written.  In
  271.         addition.
  272.  
  273.  
  274.         Copyright (c) 1987 by Michael G. Mlachak (TURBO C)
  275.         Copyright (c) 1986 by Jim LeMay (TURBO PASCAL)
  276.  
  277.         These procedures may be used and distributed without profit in
  278.         private contexts.  I must be contacted for any other use.
  279.  
  280.         If there are any problems such as snow, please let me know.
  281.     -----------------------------------------------------------------
  282.                             T U R B O  --- C
  283.         Mike Mlachak[76327,1410] (1-219-397-8952 after  6:00 PM CST)
  284.         4318 Stewart Court, East Chicago, IN. 46312
  285.     -----------------------------------------------------------------
  286.                          T U R B O  -- P A S C A L
  287.         Jim LeMay [76011,217]  (1-817-735-4833  after 1800 CST )
  288.         6341 Klamath Rd., Ft. Worth, TX, 76116.
  289.     ----------------------------------------------------------------
  290.         APPENDIX:
  291.  
  292.         Quick Reference List of all functions and parameters:
  293.         Prototypes in (windprot.h). Type definitions in (w1.h).
  294.  
  295.           ** void qinit(void);
  296.                 returns in global variables:
  297.                      maxpage: maximum number of video pages
  298.                      qwait  : if 1 wait for retrace
  299.                      qseg   : base address of screen memory
  300.                      page0seg: base address for screen 0
  301.                      cardwait: same as qwait
  302.  
  303.           void qwritelv (int row, col, attr,length; st str80);
  304.           void qwritev  (int row, Col, attr; st str80);
  305.           void qwrite   (int row, col, attr; st str80);
  306.           void qwriteC  (int row, coll, colr, attr; st str80);
  307.           void qwritecv (int row, coll, colr, attr; st str80);
  308.  
  309.           void qfillc (int row, coll, colr, rows, cols, attr; char ch);
  310.           void qfill  (int row, col, rows, cols, attr; char ch);
  311.           void qattr  (int row, col, rows, cols, attr);
  312.           void qattrC (int row, coll, colr, rows, cols, attr);
  313.  
  314.           void qstore (row, col, rows, cols; char *dest);
  315.           void qrestore (row, col, rows, cols; char *source);
  316.  
  317.           void qpage  (int page);
  318.           void qwritepage (int byte);
  319.  
  320.           void gotorc (int row, col);
  321.           int cursorchange (int new);   ** RETURNS: old cursor value
  322.           int wherex(void);
  323.           int wherey(void);
  324.           int egacheck(void) -- returns 1 if ega monitor,0 otherwise
  325.           int wiattr(int foreground,background) -- returns attribute of
  326.                                                    fore/back color
  327.           void qbox(int row, col, row, cols, attr, type) 
  328.  
  329.  
  330.         REVISIONS:
  331.  
  332.         Version 1.0 (6-1-87):
  333.           . Initial Routines
  334.           . Released under teamware concept
  335.  
  336.  
  337.